@apollo/usage-reporting-protobuf

What is @apollo/usage-reporting-protobuf?

@apollo/usage-reporting-protobuf is a package that provides Protocol Buffers (protobuf) definitions and utilities for usage reporting in Apollo GraphQL. It is used to serialize and deserialize data related to GraphQL usage reporting, which can be sent to Apollo's usage reporting endpoint.

What are @apollo/usage-reporting-protobuf's main functionalities?

Serialization

This feature allows you to create a report object and serialize it into a binary format using Protocol Buffers. The serialized data can then be sent to Apollo's usage reporting endpoint.

const { Report } = require('@apollo/usage-reporting-protobuf');
const report = Report.create({ /* report data */ });
const buffer = Report.encode(report).finish();
console.log(buffer);

Deserialization

This feature allows you to deserialize binary data back into a report object. This is useful for processing usage reports received from Apollo's usage reporting endpoint.

const { Report } = require('@apollo/usage-reporting-protobuf');
const buffer = /* some binary data */;
const report = Report.decode(buffer);
console.log(report);

Validation

This feature allows you to validate a report object to ensure it conforms to the expected schema. This helps in catching errors before serialization or deserialization.

const { Report } = require('@apollo/usage-reporting-protobuf');
const report = Report.create({ /* report data */ });
const errMsg = Report.verify(report);
if (errMsg) throw Error(errMsg);

Other packages similar to @apollo/usage-reporting-protobuf

protobufjs

protobufjs is a comprehensive library for working with Protocol Buffers in JavaScript. It provides utilities for defining, encoding, and decoding protobuf messages. Unlike @apollo/usage-reporting-protobuf, which is specific to Apollo's usage reporting, protobufjs is a general-purpose library that can be used for any protobuf-related tasks.

google-protobuf

google-protobuf is the official Protocol Buffers library for JavaScript provided by Google. It offers similar functionalities for defining, encoding, and decoding protobuf messages. It is more general-purpose compared to @apollo/usage-reporting-protobuf, which is tailored for Apollo's usage reporting.

grpc

grpc is a high-performance, open-source universal RPC framework that uses Protocol Buffers for serialization. It provides tools for defining services and messages using protobuf and supports various languages. While grpc is more focused on RPC communication, it also includes functionalities for working with protobuf messages, making it a broader tool compared to @apollo/usage-reporting-protobuf.

README

apollo-reporting-protobuf

Note: The Apollo usage reporting API is subject to change. We strongly encourage developers to contact Apollo support at [e-mail] to discuss their use case prior to building their own reporting agent using this module.

This module provides JavaScript/TypeScript Protocol buffer definitions for the Apollo usage reporting API. These definitions are generated for consumption from the reports.proto file which is defined internally within Apollo.

Development

Note: Due to a dependency on Unix tools (e.g. bash, grep, etc.), the development of this module requires a Unix system. There is no reason why this can't be avoided, the time just hasn't been taken to make those changes. We'd happily accept a PR which makes the appropriate changes!

Currently, this package generates a majority of its code with @apollo/protobufjs (a fork of protobufjs that we maintain specifically for this package) based on the reports.proto file. The output is generated with the generate npm script.

The root of the repository provides some devDependencies necessary to build these definitions; these will be installed by running npm install at the root of this workspace. When making changes to this module, run scripts via npm run SCRIPTNAME -w @apollo/usage-reporting-protobuf in the root of this monorepo in order to update the definitions in this module. The -w flag is shorthand for --workspace; this monorepo leverages NPM workspaces to manage its packages.

To update reports.proto to the current version recognized by the Studio usage reporting ingress, run npm run update-proto -w @apollo/usage-reporting-protobuf. To then regenerate the JS and TS files, run npm run generate -w @apollo/usage-reporting-protobuf. We check in the generated code and only regenerate it manually, partially to make builds faster (no need to run pbjs on every npm install) and partially so that we don't have to make sure that pbjs runs on every Node version that we support.